토스플레이스 개발자 포럼 (Beta)

현재 토스플레이스 개발자 센터에서 포스/프론트 플러그인을 올려서 테스트해보는 중입니다. 그런데 여러 사업자에 포스, 프론트 등등이 있다보니 파일을 잘못올리는 경우가 있는데 이때 기존 이력이 남아 있어서 오히려 더 헷갈리는 경향이 있는 것 같습니다. 숨기거나 삭제할 수 있는 기능이 있으면 좋을 것 같습니다.

답변 감사합니다.

안녕하세요. 토스플레이스 개발자센터입니다. 프론트 플러그인은 VAN을 통한 오프라인 결제 승인·취소만 지원합니다. 토스페이먼츠 PG로 단말 결제를 직접 승인·취소하는 방식은 지원하지 않습니다. 복합기 앞 프론트 단말의 카드·QR 결제는 앞서 안내 드린 대로 현재 구현하신 프론트 결제 API를 사용해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 문의하신 것처럼 무인매장에서 고객의 성인 여부를 먼저 확인한 뒤 결제를 진행하는 기능은 현재 토스 프론트의 공개 API나 플러그인으로 제공하지 않습니다. 프론트에서 카드나 간편결제가 승인되더라도, 고객의 성인 여부까지 확인되는 것은 아닙니다. 따라서 성인인증이 필요한 서비스라면 성인 여부는 별도 인증 수단으로 확인하고, 인증에 성공한 경우에만 프론트에 결제를 요청하는 방식을 검토해 주세요. 이때 프론트의 결제 API는 인증 이후의 결제 단계를 담당합니다. 문의 주신 성인인증 기능은 아직 안내 드릴 수 있는 도입 일정이 없습니다.

안녕하세요. 토스플레이스 개발자센터입니다. ‘방문 감사해요!’ 화면은 프론트에 내장된 결제 완료 화면으로, 플러그인에서 문구를 변경하거나 화면을 숨기고 건너뛸 수 없습니다. 매장 설정에서 문구나 표시 여부를 변경하는 기능도 제공하지 않습니다. 결제 성공 결과를 서버에 저장한 뒤 renderResultPage로 자체 결과 화면을 표시하는 것은 가능합니다. 다만 자체 화면은 프론트의 결제 완료 화면을 대체하는 것이 아니라 그다음에 표시됩니다. 다른 매장에서 보신 화면은 POS 연동 방식이나 결제수단에 따라 다를 수 있습니다. 예를 들어 IC카드 결제에서는 ‘방문 감사해요!’ 대신 카드를 빼 달라는 안내가 표시될 수 있어, 화면 차이만으로 앱 버전 때문이라고 판단하기는 어렵습니다. 하단 토스 로고도 공개 SDK나 매장 설정에서 가맹점 로고로 직접 교체하는 옵션은 없습니다. 프론트 결제 API 가이드 · 프론트 결제창과 플러그인 화면 제어에 대한 기존 답변

안녕하세요. 토스플레이스 개발자센터입니다. 14일은 승인·취소 결과를 단말기에서 다시 조회할 수 있는 기간이지, 환불 기한이 아닙니다. 단말기에는 성공 결과만 최대 1,000건까지 저장됩니다. 캐시가 만료된 뒤에도 원승인번호·승인 시각·결제수단·금액 등 취소에 필요한 값을 보관하고 있다면 전액 취소를 요청할 수 있습니다. 다만 취소 요청이 가능하다는 것과 실제로 승인된다는 것은 별개입니다. 공개 SDK 가이드에는 승인 시각부터 계산하는 공통 취소 기한이나 환불 목록의 권장 노출 기간이 없습니다. 환불 목록은 단말 캐시와 별도로 관리해 주세요. 실제 취소 가능 기간은 결제수단마다 다를 수 있으며, 해당 거래의 VAN사·카드사 정책에 따릅니다. 특정 거래의 취소 기한을 확인하려면 이용 중인 VAN사 또는 VAN 대리점에 문의해 주세요. 결제·취소 API 가이드 · 단말 조회 결과와 실제 거래 상태의 차이를 안내한 기존 답변

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 기존 POS 연동과 결제 결과 수신 방법을 안내 드립니다. 1. 타사 POS 연결 방법 말씀하신 ‘가맹점 등록’이 프론트 온보딩 과정의 ‘타사 POS’ 연결 조합 선택을 의미하신다면, 플러그인 연동 시 해당 선택지가 표시되지 않는 것이 맞습니다. 이 경우 온보딩에서 ‘타사 POS’를 선택하는 대신, 플러그인에 시리얼 통신 코드를 추가하여 POS/VAN의 요청을 처리하도록 구성해 주세요. 공개 멀티패드 예제처럼 시리얼 포트를 열고, 수신한 데이터를 van.write로 전달하는 방식입니다. POS/VAN의 통신 속도와 사용 중인 SDK 버전에 맞춰 적용한 뒤 연결 동작을 확인 부탁 드립니다. Serial API 안내 · 멀티패드 연동 예제 기존 POS 연결과 플러그인 사용에 대한 이전 답변도 참고해 주세요. 2. 외부 POS 결제 결과 수신 외부 POS가 진행한 모든 결제를 자동으로 조회·구독하는 공식 Front SDK API는 제공되지 않습니다. Payment API의 getPayment는 플러그인 결제의 paymentKey로 결과를 조회하는 기능입니다. 포인트 적립에 필요한 금액·승인번호·거래일시·승인/취소 구분·결제수단은 승인 결과를 보유한 POS 또는 VAN 연동 시스템에서 자사 서버로 전달하고, 플러그인이 해당 서버와 연동하는 구성을 우선 검토해 주세요. Payment API 안내 3. Serial API 사용 intercept: false는 기존 결제 전문을 복제해 읽기만 하는 전용 모니터링 옵션이 아닙니다. 이 설정만으로 기존 결제에 영향을 주지 않으면서 전문 전체를 관찰할 수 있다고 보기는 어렵습니다. 공개 멀티패드 예제는 intercept: true로 열고, serial.listen으로 받은 데이터를 van.write에 전달합니다. 해당 구성에서는 van.write를 사용하시고, serial.handle을 동일한 처리 경로로 간주해 대체하지 말아 주세요. van.write 완료는 전문 전달 완료이며, 결제 승인 완료를 의미하지 않습니다. 통신 속도나 수신·전달 구성에 따라 기존 연동에 영향을 줄 수 있으므로, 1번의 예제와 설정을 기준으로 확인해 주세요. 4. 결제 이후 적립 화면 결제 화면 종료 후 플러그인 화면에서 적립 결과를 표시하는 구성을 검토할 수 있습니다. 다만 화면 복귀와 결제 성공은 별개이므로, POS 또는 자사 서버에서 확인한 승인 결과를 기준으로 적립해 주세요. 결제 화면 표시 중 JavaScript·타이머가 항상 중단 없이 실행된다고 전제하지 말고, 화면 복귀 후 거래 상태를 다시 확인할 수 있도록 구성해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 자사 매장에 사용하는 경우에도 개발자센터 등록만으로 바로 설치되는 것은 아니며, 라이브 검수·배포와 VAN 대리점의 앱 활성화가 필요합니다. 개발자센터에서 플러그인을 라이브 검수 요청하고, 승인 후 배포해 주세요. 앱 이름·ID와 이용 중인 VAN 대리점의 명칭·사업자번호를 developer-support@tossplace.com으로 전달해 주세요. 해당 대리점에서 앱을 활성화할 수 있도록 권한 연결을 요청하는 절차입니다. 권한 연결 후 VAN 대리점에서 해당 매장의 플러그인 사용을 ON으로 설정하고, 프론트에서 재온보딩하여 적용해 주세요. 자세한 절차는 검수·배포 및 앱 설치 가이드를 참고해 주세요. 자체 매장 1곳에서 사용하는 경우에도 같은 절차가 필요하다는 내용은 기존 포럼 답변에서도 안내 드렸습니다.

답변 감사합니다~

안녕하세요. 토스플레이스 개발자센터입니다. 사업자 변경 이후 현재 매장의 merchantId를 확인하는 방법을 안내 드립니다. 1. merchantId 변경 여부 merchantId는 사업자번호가 아닌 매장 식별값입니다. 사업자 변경 과정에서 새 매장으로 등록하고 해당 매장으로 다시 로그인한 경우에는 기존과 다른 merchantId를 사용하게 됩니다. 2. 현재 매장의 merchantId 확인 방법 프론트 플러그인에서 sdk.app.getMerchant()를 호출한 응답의 id로 현재 로그인된 매장의 merchantId를 확인하실 수 있습니다. 함께 반환되는 매장명과 사업자번호도 대조해 주세요. 매장 정보 조회 가이드 웹훅에서 받은 merchantId로 Open API 매장 정보 조회를 호출하여 해당 매장명·사업자번호를 확인하는 방법도 있습니다. 3. 개발자센터에 기존 매장 ID가 표시되는 경우 테스트 가맹점 목록은 개발자센터 계정에 연결된 매장 정보이므로, 현재 단말에 로그인된 매장과 다를 수 있습니다. 현재 단말에서 조회한 매장 정보와 웹훅의 merchantId를 먼저 대조해 주세요. 변경 후 매장이 불러오기 목록에 표시되지 않는다면 개발자센터 계정과 연결할 매장의 사업자번호가 일치하는지도 확인 부탁 드립니다. 관련 내용은 이전 테스트 가맹점 연결 안내를 참고해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 기존 NVCAT 결제를 유지하면서 프론트 플러그인을 함께 사용하는 방법을 안내 드립니다. 1. 멀티패드 연동 구성 현재 구성에서는 플러그인에서 시리얼로 받은 NVCAT 전문을 프론트 내부 VAN 처리 기능으로 전달하는 멀티패드 연동이 필요합니다. 포인트 적립 화면만 구현하는 것과 별도로, 아래 결제 요청 전달 흐름을 구성해 주세요. 외부 POS·NVCAT → 시리얼 수신 → 플러그인 → sdk.van.write → 프론트 내부 VAN 처리 2. 확인할 설정 sdk.serial.open 호출 시 intercept: true를 설정하고, 통신 속도는 NVCAT 측 설정과 맞춰 주세요. sdk.serial.listen으로 수신한 전문을 sdk.van.write로 전달하는지 확인해 주세요. NVCAT에서 일반 카드 리딩 요청이 아닌 통합결제창을 호출하도록 구성되어 있는지 확인 부탁 드립니다. 구현 방법은 Serial API 가이드와 멀티패드 연동 예제를 참고해 주세요. 기존 POS·VCAT 연동과 프론트 직접 승인 방식의 차이는 이전 관련 답변에서도 확인하실 수 있습니다. 위 구성을 확인한 후에도 반응이 없다면 앱 ID, 프론트 시리얼번호, 재현 날짜·시각, NVCAT 호출 명령을 developer-support@tossplace.com으로 전달 부탁 드립니다. 단말 식별정보는 공개 게시글에 남기지 말아 주세요. 감사합니다.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 카드 결제 테스트와 취소·결과 조회 방법을 안내 드립니다. 1. 카드 결제 테스트 환경 카드사 가맹 없이 승인할 수 있는 별도의 테스트 TID·테스트카드는 제공해 드리기 어렵습니다. 카드 결제·취소 테스트를 위해서는 이용 중인 VAN 대리점을 통해 카드사 가맹정보를 정식으로 등록해야 합니다. 2. 운영 배포 전 테스트 가맹정보 등록 전에는 현금영수증 미발급 현금 결제로 화면 흐름과 결과 처리를 확인하실 수 있습니다. 다만 실제 카드 승인·취소 검증을 대신하지는 않습니다. 가맹정보 등록 후 본인 카드로 승인하고, 테스트가 끝나면 즉시 취소해 주세요. 결제 테스트 가이드 3. 취소 요청값 원결제의 paymentKey, response.card.timestamp와 response.card.approvalNumber를 사용하시면 됩니다. timestamp는 숫자 그대로 전달하고, paymentMethod와 금액 항목도 원거래에 맞춰 전달해 주세요. installment는 원결제의 할부 개월을 사용하고, tid를 지정하는 경우에도 원결제 TID를 사용합니다. 현금영수증 미발급 현금 결제에는 취소할 현금영수증 승인 거래가 없습니다. 결제 취소 API 4. 재시작 후 결과 조회 sdk.payment.getPayment({ paymentKey })로 같은 단말에 저장된 승인 결과를 조회하는 방식이 맞습니다. VAN에 최종 거래 상태를 다시 조회하는 기능은 아니며, 취소 결과는 getPaymentCancel로 별도 조회합니다. getBackupPaymentKey는 SDK가 백업한 결제 식별자를 읽는 보조 기능입니다. 현재 사용하시는 v0 SDK에는 getPaymentByKey가 없으므로, 예제의 해당 호출은 getPayment({ paymentKey })로 변경해 주세요. 결과 조회 API 프론트 직접 승인에 필요한 매장·TID·VAN 설정은 앞서 안내한 답변도 함께 참고 부탁 드립니다.

안녕하세요. 토스플레이스 개발자센터입니다. 개발 버전 상단의 IP·포트 표시는 프론트 앱에서 표시하는 개발용 배지입니다. 현재 이 표시만 숨기는 설정이나 SDK API는 제공되지 않습니다. 플러그인의 HTML·CSS를 수정해 제거하는 영역도 아닌 점 참고 부탁 드립니다.

안녕하세요. 토스플레이스 개발자센터입니다. 테스트 가맹점 로그인 조건과 현재 기기로 테스트하는 방법을 안내 드립니다. 테스트 가맹점이 모두 KIS 기기로만 제한되는 것은 아닙니다. 다만 로그인할 가맹점의 VAN과 프론트가 지원하는 VAN이 맞아야 합니다. 전달해 주신 기기의 로그에서도 KIS 지원 기기 안내와 함께 가맹점 인증이 거절된 내역을 확인했습니다. 현재 프론트의 VAN에 맞는 테스트 가맹점을 이용하는 방법으로 진행해 주세요. 단말을 공급한 VAN 대리점에 해당 VAN의 테스트 가맹점 생성을 요청하고, 생성된 가맹점 정보로 프론트에 로그인한 뒤 개발자센터에 연결하시면 됩니다. 기기 자체의 VAN 전환 가능 여부는 단말을 공급한 대리점에 확인 부탁 드립니다. 개발자센터 계정의 사업자번호 변경이 필요하면 아래 가이드의 필수 정보를 개발자센터 메일로 전달 부탁 드립니다. 자세한 절차는 테스트 가맹점 연결 가이드의 VAN 불일치 안내를 참고해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 내용 답변드립니다. 프론트 플러그인을 활성화하면 토스 POS와의 연동은 불가능합니다. 프론트 플러그인은 외부 솔루션이 프론트 단말기와 직접 연동되는 구조로 동작하며, 플러그인이 활성화된 환경에서는 토스 POS와의 연결이 끊어집니다. 따라서 두 가지 질문 모두 현재는 지원되지 않습니다. POS는 그대로 쓰고 프론트만 플러그인 적용 → 불가 POS 플러그인 + 프론트 플러그인 동시 사용 → 불가 혹시 어떤 기능을 구현하려고 하시는지 배경을 공유해 주시면, 현재 제공 중인 연동 방식으로 구현 가능한지 검토 후 대안을 안내드릴 수 있습니다. 감사합니다.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 프론트 플러그인 결제 후 영수증 출력 방법을 안내 드립니다. 1. 카드 매출전표 출력 플러그인 결제 시 전자영수증은 지원하지 않습니다. 프론트에 프린터가 연결되어 있으면 결제 완료 후 기본 영수증 1장이 자동 출력됩니다. 추가 출력이나 재출력이 필요한 경우에는 Printer API의 printReceipt를 이용해 별도로 구현해 주세요. 2. printReceipt 호출값 결제 응답 전체가 아니라, 결제에 사용한 paymentKey와 출력 수량 count를 전달합니다. 1장 출력 시 paymentKey와 count: 1을 전달하시면 됩니다. 주문 정보 orderInfo와 추가 문구 additionalText는 선택 사항입니다. 파라미터와 호출 예제를 참고 부탁 드립니다. 3. 외부 프린터 연결 프론트에 연결한 시리얼·블루투스 프린터로 출력하는 경로가 있습니다. 유선 연결 예시는 CPP-3000이며, 프론트 Serial 포트에 연결한 후 프린터 설정에서 시리얼 케이블을 선택하고 테스트 출력으로 확인합니다. 사용할 프린터의 호환 여부는 구매·설치 대리점에 먼저 확인 부탁 드립니다. 연결 가이드의 유선 연결 및 프론트 설정 부분을 참고해 주세요. 해당 가이드의 POS 등록 단계는 현재 문의하신 프론트 단독 구성과 구분해 보셔야 합니다. paymentKey로 결제 정보를 조회해 출력하는 방식은 기존 Printer API 답변도 참고 부탁 드립니다.

안녕하세요. 토스플레이스 개발자센터입니다. 문의하신 터미널2의 결제내역 표시 여부를 안내 드립니다. 프론트 플러그인으로 처리한 결제내역을 터미널2에서 조회하는 기능은 지원하지 않습니다. 동일 매장에서 사용하거나 프론트2와 터미널2를 연결하더라도, 해당 플러그인 결제내역이 터미널2에 표시되지는 않습니다. 결제내역 확인은 현재 이용 중인 토스 POS에서 진행해 주세요.

요새 병의원 쪽도 많이 보이는거 같은데 플러그인일까요??

안녕하세요. 토스플레이스 개발자센터입니다. WebSocket 서버의 보안 기능과 로컬 저장소의 사용 범위를 나누어 안내 드립니다. 1. WSS 및 연결 단계의 인증 sdk.websocket.start()로 여는 서버는 WS 방식이며, TLS 인증서·개인키 설정이나 핸드셰이크 단계의 인증 헤더 검증 기능은 제공하지 않습니다. 따라서 해당 서버에 WSS를 설정하거나, SDK의 연결 콜백에서 핸드셰이크 이전에 연결을 거절하는 방식으로 구성할 수는 없습니다. 연결 후 인증 메시지를 확인하고 실패 시 disconnect()로 종료할 수는 있습니다. 이 경우 인증이 끝나기 전에는 결제·취소 명령을 처리하지 않도록 해야 하며, 연결 후 인증만으로 통신이 암호화되는 것은 아닙니다. 2. 암호화가 필요한 경우의 구성 자체 WSS 서버에 POS와 프론트 플러그인이 각각 접속하고, 해당 서버에서 인증과 요청 전달을 처리하는 구성을 검토해 주세요. 프론트 플러그인은 브라우저 표준 WebSocket으로 접속하며, 접속 대상에 맞는 유효한 인증서와 ACL 설정이 필요합니다. 인증서 검증을 해제하는 방식으로 구성하지 말아 주세요. 파트너 시스템 연동 가이드와 WebSocket API를 참고해 주세요. 프론트를 WS 서버로 사용하는 기존 구성은 이전 포럼 답변에서도 안내했지만, 해당 구성이 WSS를 제공한다는 의미는 아닙니다. 3. localStorage와 Storage API Storage API는 WebView의 localStorage가 아니라 단말기의 별도 네이티브 저장소를 사용합니다. localStorage 사용 자체를 일괄 금지하는 것은 아니지만, 사용만으로 검수가 승인되거나 데이터 보존이 보장되는 것은 아닙니다. SDK의 키·값 저장 기능이 필요하다면 Storage API를 사용하되, 전환만으로 주문·결제 복구의 안정성이 보장된다고 보시면 안 됩니다. 4. 데이터 유지와 격리 Storage API의 저장된 값은 일반적인 플러그인 새로고침, 앱 재시작 및 단말기 재부팅 후에도 보관하는 구조입니다. 다만 재온보딩 과정에서는 초기화됩니다. 업데이트·로그아웃·삭제·재설치의 모든 경우에 두 저장소의 데이터가 유지된다고 전제하지 말고, 값이 없는 경우 서버에서 복원할 수 있도록 구성해 주세요. Storage API를 앱·매장·계정별 자동 격리가 보장되는 저장소로 사용하지 마세요. 매장이나 계정이 바뀌었을 때 이전 상태를 그대로 적용하지 않도록 구분과 초기화 처리가 필요합니다. 5. 저장 용량·쓰기 보장·결제 복구 공통으로 보장하는 저장 용량이나, 저장 성공 직후 전원 차단까지 포함한 쓰기 보존·원자성을 제공하는 거래 저장소로 안내 드리기는 어렵습니다. 주문·결제의 기준 데이터는 서버에 저장하고, 로컬 저장소는 비민감 설정이나 복구 보조 상태용으로 사용해 주세요. 인증 토큰·API 키·민감한 결제정보를 보관하는 용도로 사용하지 마세요. Storage API는 암호화 저장소가 아닙니다. 승인 응답이 유실됐다면 동일 단말에서 같은 paymentKey로 getPayment를 호출해 결과를 복구할 수 있습니다. 해당 기능은 최근 성공 승인 결과의 로컬 캐시 조회이므로 영구적인 결제 원장이나 다른 단말의 조회 수단을 대신하지는 않습니다. Storage API · 프론트 FAQ · 승인 결과 복구 안내